TLDR Command in Linux: 4 Clients Tested, Mistakes to Avoid

The tldr command shows short, example-first help pages for command-line tools, written by the community at tldr-pages. What most guides miss is that "tldr" is not one program. It is a set of pages plus many independent clients, and the client you get depends on how you install it. They do not share options. I installed the tldr command four ways (Debian's package, pip, npm and Fedora's package) and ran the options from the old version of this post against each one. Most of those options do not exist.

tldr command on Debian 13: no tldr package, tealdeer 1.7.2 installed instead, --offline rejected, cache update and the tar page
Real lab output: which tldr client you get, and which options it accepts.

Which tldr command will you get?

Debian 13 and derivatives. apt install tldr failed:

tldr:
  Candidate: (none)
tealdeer:
  Candidate: 1.7.2-1+deb13u1
E: Package 'tldr' has no installation candidate

The package to install is tealdeer, a client written in Rust, which provides the command:

$ readlink -f $(command -v tldr); dpkg -S $(readlink -f $(command -v tldr)) 2>/dev/null
/usr/bin/tldr
tealdeer: /usr/bin/tldr

$ tldr --version 2>&1 | head -2
tealdeer 1.7.2

Fedora. dnf install tldr worked and installed tldr-3.4.4-3.fc45.noarch, which reported tldr 3.4.4 (Client Specification 2.3): the Python client.

pip. pip install tldr in a virtual environment gave the same Python client, tldr 3.4.4 (Client Specification 2.3).

npm. npm install -g tldr installed the Node.js client, which printed v3.5.0 and Client Specification: 2.0.

Three different programs, all called tldr. Check which one you have with tldr --version before you copy options from any guide.

First run: download the pages

tealdeer does not ship the pages. The first lookup failed with a clear message:

Page cache not found. Please run `tldr --update` to download the cache.

After tldr --update ("Successfully updated cache."), pages work offline from the local cache, which held 6813 commands (tldr --list | wc -l). The tar page starts like this:

  Archiving utility.
  Often combined with a compression method, such as `gzip` or `bzip2`.
  More information: <https://www.gnu.org/software/tar/manual/tar.html>.

  [c]reate an archive and write it to a [f]ile:

      tar cf path/to/target.tar path/to/file1 path/to/file2 ...

The bracketed letters, [c]reate and [f]ile, show where the short options come from. That is the main value of the tldr command: the common case in five lines, with the man page link for everything else.

The old options, tested

The earlier post listed --os, --offline, --style compact and --search. Results:

Optiontealdeer 1.7.2 (Debian)Python 3.4.4 (pip, Fedora)Node 3.5.0 (npm)
--os linuxunexpected argumentnot tested (has --platform)unknown option
--offlineunexpected argumentunrecognized argumentsunknown option
--style compactunexpected argumentnot testednot tested
--searchunexpected argumentaccepted, "No commands matched your search term."works

tealdeer's exact message was error: unexpected argument '--offline' found, and the Node client said error: unknown option '--os'. Only the Node client did a real search: tldr --search 'list files' printed "Searching for: list files" and a list of matching pages. No client needs an offline flag; once the cache is downloaded, lookups are offline anyway.

The options that do work

For tealdeer, its own help is the reference:

  -l, --list                 List all commands in the cache
  -p, --platform <PLATFORM>  Override the operating system, can be specified multiple times in order
                             of preference [possible values: linux, macos, sunos, windows, android,
                             freebsd, netbsd, openbsd]
  -u, --update               Update the local cache
  -c, --clear-cache          Clear the local cache
  -r, --raw                  Display the raw markdown instead of rendering it

So the platform option is -p/--platform, not --os. Watch out for -c: in tealdeer it clears the cache, and --compact is not an option (tldr --platform linux --compact tar was rejected). The Python client also uses --platform: tldr --platform linux tar printed the tar page in a compact one-line-per-example layout. The tealdeer documentation covers its config file, including automatic cache updates, which the first-run message also suggests.

Install the tldr command: one line per system

From the four installs in this test, these are the commands that put a working tldr command on the system:

# Debian 13 (and other systems where the package is called tealdeer)
apt install tealdeer && tldr --update

# Fedora: the Python client
dnf install tldr

pipx install tldr        # or: python3 -m venv ~/tldr && ~/tldr/bin/pip install tldr
# Any system with Python: tldr.sh recommends pipx (I used pip in a venv)
pipx install tldr        # or: python3 -m venv ~/tldr && ~/tldr/bin/pip install tldr
pipx install tldr        # or: python3 -m venv ~/tldr && ~/tldr/bin/pip install tldr

# Any system with Node.js
npm install -g tldr

Pick one. Installing two of them puts two different programs named tldr on your PATH, and which one runs depends on the order of your PATH entries. If the tldr command suddenly rejects an option that worked yesterday, command -v tldr and tldr --version tell you which client answered.

The Python client renders pages differently from tealdeer. With --platform linux tar it printed one example per line:

  - [c]reate an archive and write it to a [f]ile:    tar cf path/to/target.tar path/to/file1 path/to/file2 ...
  - E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely:    tar xvf path/to/source.tar.ext

The content is the same tldr page; only the layout differs, so the tldr command you choose is a matter of options and speed of setup, not of content.

Using the tldr command day to day

  • tldr tar, tldr find, tldr rsync: the quick reminder before you reach for the man page.
  • tldr --update now and then, or enable automatic updates in tealdeer's config.
  • tldr -p linux <cmd> when you are on macOS but want the Linux version of a page (tealdeer and the Python client).
  • An alias such as alias h=tldr works with any client.

tldr pages are summaries. They show the common case and skip the traps; for find, for example, the details in the Linux find command guide (prune, -exec, -delete order) are exactly what a five-line page leaves out. The same goes for tar: listing the contents of a tar.gz file covers the errors you meet in practice. Use the tldr command to remember the syntax, then the man page or a tested guide to understand it. The project site tldr.sh has a live demo and calls the Python client its "most mature client", installed there with pipx install tldr; other clients are listed in the project wiki.

Comments

Popular posts from this blog

How to Play Minecraft Bedrock Edition on Linux: A Comprehensive Guide for Tech Professionals

Linux desktop frozen? My 5 go-to tricks to try - before forcing a hard reboot

The Ultimate Guide: How to Set Up DXVK in Wine on Linux for Enhanced Gaming Performance